Dexter's log

Earlier this year, I deployed my first Cloudflare (CF) Page built with Hugo, and it failed with several build errors. The root cause was a different Hugo version running on my computer compared to the one in the CF build pipeline. Let’s solve this.

Hugo build worked on my machine™ but was failing on CF with an error:

Error: Unable to locate Config file. Perhaps you need to create a new site.
       Run `hugo help new` for details.
Failed: build command exited with code: 255
Failed: error occurred while running build command

You could also encounter errors such as

Failed to add template "index.html" in path "index.html": template: index.html:10: function "site" not defined

or any other Hugo error caused by a different Hugo version running in CF than on your computer.

These two specific errors are caused by migrating from Hugo’s original config.toml file to the newer config in hugo.toml (same error occurs when using the new config folder) and by using the global site function, which didn’t exist in earlier Hugo versions, respectively.

Creating a new Cloudflare Pages application

You have followed CF’s guide on deploying a Hugo site, or you figured it out on your own; it’s not that hard :) The guide shows how to use a specific Hugo version now, but that wasn’t always the case.

• under the Workers & Pages menu -> Overview -> Create application
• switch the tab from Workers to Pages -> Connect git
• setup GitHub access
• select the repository -> Begin Setup
• Chose Hugo from the “Framework preset” dropdown, click Save and Deploy, and wait a couple of seconds (or a day when CF has an outage :))

If the deployment is successful, great! You can stop reading now. However, to find out how to avoid future build problems, just skip to the end.

You’re still reading, so you’re probably running into issues in the CF build that you didn’t have when building your Hugo site on your own machine. This is likely because you have a different Hugo version compared to CF’s build pipeline. Take a look at the CF build logs for the Hugo version. If you’re using npm, and getting npm-related errors, check its version too.

The build logs in the “Deploying to Cloudflare’s global network” page will show something like:

...
Detected the following tools from environment: [email protected], [email protected]
...
hugo v0.118.2-da7983ac4b94d97d776d7c2405040de97e95c03d+extended linux/amd64 BuildDate=2023-08-31T11:23:51Z VendorInfo=gohugoio

This log tells us that the used Node.js version is 18.17.1, npm version is 9.6.7 and Hugo version is v0.118.2. If these are the same as your local versions, and you encounter build errors, then this guide won’t help you, sorry.

Otherwise, the simplest fix is to use the same Hugo and npm versions in CF as you do locally. To do this, Cloudflare Pages use environment variables, and then they download the specific versions in the build pipeline. Navigate to the settings of you CF Page -> Settings -> Environment variables and set the versions you use locally. Hugo version is configured via HUGO_VERSION, and npm through its Node.js version with NODE_VERSION env variable. You should see no environment variables set there yet:

This blog is using Hugo v0.110.0 and Node.js 20, so let’s add these versions by clicking the blue “Add variables” buttons. Notice that the Hugo version is specified without the v prefix.

HUGO_VERSION    0.110.0
NODE_VERSION    20

Don’t forget to set it for both Production and Preview environments (if you use them); otherwise, it won’t work for builds from your main branch or from your feature branches. The result should look like this:

Summary

The default Hugo version in Cloudflare Pages’ build pipeline used to be very old, around version v0.45, which caused problems with today’s themes, like the errors at the top. Now (as of time of writing this article), they have bumped the version to v0.118.2. While this is a better version for today, it can cause problems with themes built with older Hugo.

I am building this webpage with Hugo v0.110.0 locally, and the v0.118.2 is already showing some warnings, so I have fixed the version to v0.110.0. Until I update the theme, of course. But I would rather write some content and stay on older Hugo than fix something that can work for years.

In the end, it is always a good idea to use a fixed version of your dependencies. Hugo is moving fast, often in a backwards incompatible way. Thus, if your deployment is working today without fixed versions in the build pipeline, it will break in the future, guaranteed :)